Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / wind5x.arc / WNDW5X.DOC < prev next >

Wrap

Text File | 1991-01-09 | 94KB | 2,421 lines

MULTI-LEVEL VIRTUAL WINDOWS USER'S GUIDE Version 5.X December 20, 1988 Copyright (C) 1988 Eagle Performance Software All Rights Reserved. _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER WNDW Multi-level Virtual Windows User's Guide, Version 5.X T A B L E O F C O N T E N T S 1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 4 Features . . . . . . . . . . . . . . . . . . . . . . 4 Using the Manuals . . . . . . . . . . . . . . . . . . 4 Licensing . . . . . . . . . . . . . . . . . . . . . . 5 Customer Service . . . . . . . . . . . . . . . . . . 5 ASP . . . . . . . . . . . . . . . . . . . . . . . . . 6 2. GETTING STARTED . . . . . . . . . . . . . . . . . . . . 7 Distribution Files . . . . . . . . . . . . . . . . . 7 Demonstration . . . . . . . . . . . . . . . . . . . . 7 3. PROGRAMMING WINDOWS . . . . . . . . . . . . . . . . . . 8 Basic Programming . . . . . . . . . . . . . . . . . . 8 Window Definitions . . . . . . . . . . . . . . . . . 9 Basic Routines . . . . . . . . . . . . . . . . . . . 10 MakeWindow Parameters . . . . . . . . . . . . . . . . 10 Window Modes . . . . . . . . . . . . . . . . . . . . 11 Defaults . . . . . . . . . . . . . . . . . . . . . 11 SetWindowModes . . . . . . . . . . . . . . . . . . 12 List of Modes . . . . . . . . . . . . . . . . . . . 12 Shadows . . . . . . . . . . . . . . . . . . . . . . 13 ZoomMode . . . . . . . . . . . . . . . . . . . . . 13 RelMode . . . . . . . . . . . . . . . . . . . . . . 13 PermMode . . . . . . . . . . . . . . . . . . . . . 13 SeeThruMode . . . . . . . . . . . . . . . . . . . . 14 Hidden Mode . . . . . . . . . . . . . . . . . . . . 14 Virtual Mode . . . . . . . . . . . . . . . . . . . 15 Cursor Modes . . . . . . . . . . . . . . . . . . . . 16 3. WRITING TO WINDOWS . . . . . . . . . . . . . . . . . . 17 Direct Writing . . . . . . . . . . . . . . . . . . . 17 Cursor and EOS Positioning . . . . . . . . . . . . . 17 Clearing . . . . . . . . . . . . . . . . . . . . . . 18 Scrolling . . . . . . . . . . . . . . . . . . . . . . 19 Line Drawing . . . . . . . . . . . . . . . . . . . . 20 Custom Routines . . . . . . . . . . . . . . . . . . . 21 4. VIRTUAL WINDOWS . . . . . . . . . . . . . . . . . . . . 23 Application . . . . . . . . . . . . . . . . . . . . . 23 Programming . . . . . . . . . . . . . . . . . . . . . 23 5. WINDOW MANAGEMENT . . . . . . . . . . . . . . . . . . . 27 Access Methods . . . . . . . . . . . . . . . . . . . 27 Display Control . . . . . . . . . . . . . . . . . . . 27 Write Control . . . . . . . . . . . . . . . . . . . . 28 Window Modes and Flags . . . . . . . . . . . . . . . 29 High Speed Screen Design . . . . . . . . . . . . . . 29 Multiple Video Pages . . . . . . . . . . . . . . . . 30 6. DATA MANAGEMENT . . . . . . . . . . . . . . . . . . . . 31 Data Allocation . . . . . . . . . . . . . . . . . . . 31 Record Handling . . . . . . . . . . . . . . . . . . . 31 2 WNDW Multi-level Virtual Windows User's Guide, Version 5.X 7. UTILITY UNITS . . . . . . . . . . . . . . . . . . . . . 34 Goof Unit . . . . . . . . . . . . . . . . . . . . . . 34 Wutil Unit . . . . . . . . . . . . . . . . . . . . . 34 APPENDIX A: Application Products . . . . . . . . . . . . . 36 APPENDIX B: Revision History . . . . . . . . . . . . . . . 38 APPENDIX C: Credits . . . . . . . . . . . . . . . . . . . 40 3 WNDW Multi-level Virtual Windows User's Guide, Version 5.X 1. I N T R O D U C T I O N FEATURES Welcome to WNDW multi-level virtual windows! You have just obtained a copy of the highest performance window utilities available today for Turbo Pascal 5.0 (TP5). Both novice and professional programmers will appreciate these simple and very powerful utilities that gives you full window control and management in all text modes. Here are some of the features you will discover: . Uses the powerful direct screen writing routines of QWIK5X. . Up to 254 fixed or virtual windows can be on the screen at one time. . Extremely high-speed virtual screens in RAM. . Virtual windows are fully updated even if covered! . Virtual windows have virtual titles. . Fully supported hidden windows saved in RAM. . Fully supports all video pages. . Adjustable-rate moving, resizing, and scrolling. . All windows can be randomly accessed. . 28 window-relative writing routines. . 15 different border styles with shadows. . Full line drawing procedures. . Full cursor mode control for each window. . Writes in all text modes and column modes. . Only 13k bytes of code if all 69 utilities are used. . Used in all other Eagle products. WNDW is a very high performance window unit with high speed and tight code. All types of windows, including fixed or virtual, hidden or shown, work compatibly in the same package. With WNDW, you can choose the absolute writing routines of QWIK, the window-relative writing routines of WNDW, and even customize your own. | Version 5X - This version is simply a TP5 compiled version of WNDW42. | WNDW50 will be out at a later date with other features specific to TP5. USING THE MANUALS Disk Based Guides - The manuals for WNDW are on disk so that you can conveniently scan for the topic you are seeking. You can do this with any list or search utility with a search function. You can also make a printed copy. If you have not already printed this manual, refer to the READ.ME file for instructions. At the present time, no bound manuals are being offered with registration. User's Guide - This manual, the one your are reading now, assumes that as a programmer you are already familiar with Turbo Pascal 5.0, and that you have a working knowledge of your disk operating system (DOS). It also Chapter 1, Introduction Page 4 WNDW Multi-level Virtual Windows User's Guide, Version 5.X assumes that you are familiar with QWIK screen utilities in QWIK5X.ARC. This manual will provide the basic instructions for creating and managing multi-level windows. You can even copy examples from this file direct to the Turbo editor for testing. Reference Guide - This manual describes in detail all procedures, functions and variables used in WNDW. It is a alphabetically arranged for easy access in a format similar to the TP5 manual. Use this manual when you have become familiar with the basic principles in the User's guide. LICENSING Registration - These routines and the documentation have been released for distribution as Shareware. You have been given the chance to sample the full capability of WNDW without risk! If you find that WNDW is a valuable tool, then you are expected to register. You will find a reasonable licensing schedule found in LICENSE.ARC to meet private or commercial needs. When registering, be sure to specify the version for Turbo Pascal (such as TP4 or TP5) you wish to receive. Source Code - All registered users will receive source code when the signed license agreement is returned with the registration. All source code compiles under TP5 as well as TP4. The compiled units in the distributed file were compiled with TP5 and only work in TP5. CUSTOMER SERVICE If you have questions, comments, or suggestions, the Eagle can be contacted by three means - (1) CompuServe, (2) telephone, (3) The Eagle BBS, or (4) mail. CompuServe - The most dependable way to contact the Eagle is through CompuServe. James (Jim) H. LeMay has written the TP5 version of WNDW. He can be contacted on the Borland Forum by typing GO BPROGA from the CompuServe main menu. You will enter the Forum for Turbo Pascal. You can contact Jim with his PPN number of 76011,217. Messages can also be left through EasyPlex. Telephone - Jim can also be reached by phone at (817) 735-4833 on weekdays and Saturday from 9:00 a.m. to 8:00 p.m CST. The Eagle BBS - After 01-10-89, you can also contact us on our 24-hour BBS at (214) 539-9878, 1200 N81. Mail - For registration or problems, please write: Eagle Performance Software TP products P.O. Box 122237 Ft. Worth, TX 76121-2237 In your written request for resolving problems, be sure to include: Chapter 1, Introduction Page 5 WNDW Multi-level Virtual Windows User's Guide, Version 5.X . A 5 1/4 inch diskette of compilable source code of the problem. . The Eagle product and version number. . The computer make and model. . The type of video card, video monitor and keyboard. For identical Turbo C products, write: Eagle Performance Software TC products P.O. Box 292786 Lewisville, TX 75029-2786 Or, contact Jim Gallagher at (214)-539-7855 ASP WNDW is a Shareware program conforming to the standards of the Association of Shareware Professionals (ASP). You can get more information about ASP by writing to: Association of Shareware Professionals 325 118th Ave. S.E., Suite 200 Bellevue, WA 98005. Chapter 1, Introduction Page 6 WNDW Multi-level Virtual Windows User's Guide, Version 5.X 2. G E T T I N G S T A R T E D This section will acquaint you with the files on distribution disk and show you a couple of demonstrations to quickly see what WNDW can accomplish. DISTRIBUTION FILES In this version, WNDW5X.ARC contains: Read. .me: Note of printing instructions for manual. KeyB .tpu: Keyboard unit for WDNWMGR.PAS demo. Goof .pas: Unit to display errors. Qwik5x .tpu: Unit for quick screen writing. Strs .tpu: Unit from QWIK5X for number-to-string conversions. Wutil .tpu: Independent utilities unit used in WNDW. W5X-var .inc: This file is the actual source code which lists all of the types, constants, and variables used for WNDW5X.TPU. Wndw5X- .pas: Shows the interface portion of WNDW5X. Wndw5X .tpu: This unit has the full power of all of its capabilities. Please note that because WNDW5X.TPU uses W5X-VAR.INC, MaxWndw, MaxVirtualWndw, MaxPageUsed, and the WindowNames names have all been assigned. In order to make any changes in the data requirements, the complete source code will be required. Wndw5X .doc: This document - a user's guide to WNDW. WndwRef .doc: WNDW Reference Guide document covering each routine and variable in detail. WndwDemo.pas: Demo of WNDW5X.TPU and QWIK5X.TPU which show screen design performance. WndwMgr .pas: Demo of full window management. License .arc: ARC file containing license agreement and ordering details. DEMONSTRATION To get the feeling of the speed and features of WNDW, let's run the demonstration programs that came with the utilities. Do the following steps: 1. Copy QWIK5X.TPU to QWIK.TPU. 2. Copy WNDW5X.TPU to WNDW.TPU 3. Make, compile and run WNDWDEMO.PAS to get a feel for screen design performance and speed. 4. Make, compile and run WNDWMGR.PAS to get a feel for true virtual windows and window management. Press Alt-1 to access the bottom window. With Scroll Lock on, it can be moved, resized and scrolled. Chapter 2, Getting Started Page 7 WNDW Multi-level Virtual Windows User's Guide, Version 5.X 3. P R O G R A M M I N G W I N D O W S This sections will get you familiar with the basics of window programming by starting with very basic windows and then taking you step-by-step through the variety of options and modes that are available. BASIC PROGRAMMING First Program - Let's write a short program to see how simple it is to write with WNDW. While in the TP editor, enter the following code: EXAMPLE 1: Your first window ---------------------------------------------------------------------- {$M 16384,8000,8000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,true); { Initialize and Clear window } MakeWindow (5,20,15,40,White+BlueBG,Cyan+BlueBG,SingleBrdr,aWindow); WWriteC (7,'Making windows is easy!'); end. Assuming you have already copied QWIK5X.TPU to QWIK.TPU and WNDW5X.TPU to WNDW.TPU, make and run the code. You can then see these results: . The base window is cleared with Black on LightGray attributes. . The window is placed at absolute row 5, column 20 . The window size is 15 rows high and 40 columns wide. . The window text color is White on a Blue background. . The window border color is Cyan on a Blue background. . The border is the Single line width style. . The window name is aWindow. . The message was centered on window-relative row 7. Row/Col vs. X/Y - You probably noticed that the row parameter is first and the column parameter is second. Since WNDW is entirely for text modes, it is more intuitive to specify the row first and the column second just like any word processor. The X/Y scheme is better suited for graphics. Attributes - Notice that our example uses the constant "BlueBG". WNDW uses QWIK which provides eight convenient background color constants to use along with Turbo's 16 foreground colors. The same names are used, but the "BG" suffix is added: BlackBG RedBG BlueBG MagentaBG GreenBG BrownBG CyanBG LightGrayBG These allow WNDW to make the most of Turbo's constant folding. By simply adding the foreground and background constants together, the compiler saves the result as a single word. And, by simply reading the MakeWindow statement, what you see is what you get (WYSIWYG). Protected Underlay - That first program was pretty simple wasn't it? Chapter 3, Programming Windows Page 8 WNDW Multi-level Virtual Windows User's Guide, Version 5.X Several things happened that you probably didn't notice. The area under the window, called the underlay, was actually saved. Later on when the window is no longer needed, it can be removed by restoring the underlay. This makes it just like a sheet of paper on a desk. Let's add some statements to show if the underlay is really protected. In addition, let's add a little more pizazz to the window by adding a shadow, zoom effect, and a title: EXAMPLE 2: Protected underlay ---------------------------------------------------------------------- {$M 16384,8000,8000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,true); WWriteC (12,'Base Window'); SetWindowModes (ZoomMode+ShadowRight); MakeWindow (5,20,15,40,White+BlueBG,Cyan+BlueBG,SingleBrdr,aWindow); TitleWindow (Top,Left,Yellow+BlueBG,' My First Window '); WWriteC (7,'Making windows is easy!'); delay (2000); RemoveWindow; { Remove the window and restore underlay. } end. Did you see that the message "Base Window" was still there? In fact that whole entire underlay was protected because it was saved in the heap while we were writing on the CRT. In addition: . The window modes controlled the Shadow and Zoom effect. . The title is placed on the Top border, Left justified, with Yellow on Blue attributes. . The "Base Window" message was centered on window-relative row 12. Basic Principles - Was that simple enough for you? Well, you'll be glad to know that you have already tried all the basic principles to making windows. And the rest is just that easy. But you haven't seen anything yet. WINDOW DEFINITIONS Window - Just what is a window anyway? It's an area reserved on the screen as a frame of reference to write text. Right on the screen, the power of this program allows you to move, rearrange, hide, move, and resize, without losing any data. View - In virtual windows, this window text area is also called the view. More about virtual windows is explained later. Border - The border is the lines surrounding the window or view to clearly separate the window contents from other areas of the CRT. However, a window does not require a border. Title - Conveniently, a window can be titled on the border - either the top or the bottom. The title area extends the full length of the window not including the two vertical borders. The title is written at a border- Chapter 3, Programming Windows Page 9 WNDW Multi-level Virtual Windows User's Guide, Version 5.X relative location. If a window does not have a border, then the title area is just the top or bottom row of the window text area. Cursor - Each window has its own cursor location and mode (shape). Shadow - To give a window that off-the-screen appearance, a shadow can be added onto the outer edge of the window or window border. Generally Speaking - Throughout this document, the word "window" will loosely refer to all of the above parts as the full window. It should be understood that all writing to the windows uses coordinates relative to the upper left corner of the window text area which is (1,1) exclusive of the border. BASIC ROUTINES Basic Routines - There are five basic procedures that are fundamental to creating multi-level windows: InitWindow - Initializes global data for the program. SetWindowModes - Determines what types of windows are made. MakeWindow - Creates the window. TitleWindow - Places titles on the window. RemoveWindow - Removes window from CRT and memory. InitWindow - First, before any window procedures are used, InitWindow should be executed to initialize all global data for the entire programs. It only needs to be done once. InitWindow (Wattr: integer; ClearScr: boolean) The initial base window has no border and the window attribute is Wattr. You can optionally clear the window by setting ClearScr to TRUE. The procedure initializes over 50 variables. For details, you can examine the source code. MAKEWINDOW PARAMETERS Declaration - The MakeWindow procedure actually makes the window on the screen. Let's take a look at its declaration: MakeWindow (Row,Col,Rows,Cols: byte; Wattr,Battr: integer; BrdrSel: Borders; WindowName: WindowNames) The procedure's parameters control location, size, attributes, border style, and window name. Notice that the size used Rows/Cols rather than another (Row2,Col2) coordinate. This makes it very easy to change the location without having to recalculate the size. Attributes - Wattr and Battr are the attributes for the window text area and border, respectively. The attributes that are recognized are the same ones used in QWIK - even SameAttr is supported. Chapter 3, Programming Windows Page 10 WNDW Multi-level Virtual Windows User's Guide, Version 5.X Border Styles - There are 15 different border styles that can be used for the border, including two custom borders and even no border at all. Here is the list of Border names that are predefined: NoBrdr - No border at all. Just the text area. BlankBrdr - Blank character on all sides. SingleBrdr - Single lines on all sides. DoubleBrdr - Double lines on all sides. HdoubleBrdr - Horizontal double lines. Single vertical lines. VdoubleBrdr - Vertical double lines. Single horizontal lines. SolidBrdr - Solid box character on all sides. EvenSolidBrdr - Vertical solid box. Horizontal half box. ThinSolidBrdr1 - Half box on all sides. Squeezed horizontally. ThinSolidBrdr2 - Half box on all sides. Squeezed vertically. LhatchBrdr - Light hatch character on all sides. MhatchBrdr - Medium hatch character on all sides. HhatchBrdr - Heavy hatch character on all sides. UserBrdr1 - User defined border. UserBrdr2 - User defined border. All of the borders except the user borders are reserved for use in future Eagle products. UserBrdr1 and UserBrdr2 may be customized to your needs. Each border has 15 different parts for the line drawing set including tees and interior lines. Tip: Hatch Borders - Since MDA and VGA both use a 9x16 character cell size, the hatch characters (ASCII 176, 177, 178) are only 8x16 in a 9x16 cell. This unfortunately produces a horizontal gap between the characters not seen on the CGA. Be aware of the effect. Window Name - The name of each window should be different in order to uniquely identify the window for window management. But since our simple test program only displayed the window momentarily, the window name is not significant and did not need to be unique. So, the generic name "aWindow" was used. The name Window0 is used to identify the initial base window which is the full CRT screen. WINDOW MODES Defaults - Without needing to specify anything, the window is created with several defaults. Let's see what they are: . Fixed size and placed absolute to the CRT. . Shown on the CRT. . The underlay is saved. . No shadow or zoom effect. . No virtual screen. . Cursor is turned on with the default cursor mode. . Window is cleared. . Moving and Accessing is permitted. Well, if these are all defaults, then that means they can be changed. And they can. We've already found out how to add shadow and zoom. Let's try changing some others and see what happens. Enter the following code into Chapter 3, Programming Windows Page 11 WNDW Multi-level Virtual Windows User's Guide, Version 5.X the editor: EXAMPLE 3: Different modes and a hidden window ---------------------------------------------------------------------- {$M 16384,8000,8000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,true); SetWindowModes (HiddenMode or ZoomMode or CursorOffMode); MakeWindow (5,20,15,40,White+BlueBG,Cyan+BlueBG,SingleBrdr,Window1); WWriteC (12,'Where is it?'); WriteToHidden (Window1); { Write to the hidden window.} TitleWindow (Bottom,Right,Yellow+BlueBG,' My Second Window '); WWriteC (3,'Here it is ...'); WBrdrH (7); { Add an extra horizontal border.} WWriteC (10,'It was hidden!'); delay (2000); ShowWindow (Window1); { Put it back on the screen. } delay (2000); RemoveWindow; end. When you run it, the window is immediately created. But instead we see the message "Where is it?". And to answer that question, the window was created in RAM instead of on the CRT. In addition, the code also wrote messages direct to the hidden window. The window remains hidden until it is called which we did with ShowWindow. Afterward, we removed it from memory with RemoveWindow. I'll bet you didn't know that you have already done some writing to a virtual screen. That's right - the hidden window was a virtual screen! Pretty easy, huh? And it was done by simply setting a mode. SetWindowModes - This procedure can be used any time prior to MakeWindow. It only needs to be done once since the value is retained in WindowModes until changed again. List of Modes - Did you notice the zoom effect this time and that the cursor was turned off? Let's take a look at all the available modes: Mode Constant Description ------------- ----------------------------------------------- ShadowLeft Shadow on the left side ShadowRight Shadow on the right side ZoomMode Zoom effect on Make, Show and AccessWindow CursorOffMode Leaves cursor off for window RelMode Window-relative frame of reference, no underlay PermMode Can't be moved or removed, no underlay SeeThruMode Doesn't clear screen inside window HiddenMode Create window as hidden VirtualMode Create Virtual window and screen NoHideMode Ignores request to hide window NoAccessMode Ignores request to access window NoMoveMode Ignores request to move/resize window We've already seen what the first four can do. Let check to see what the Chapter 3, Programming Windows Page 12 WNDW Multi-level Virtual Windows User's Guide, Version 5.X others can do. ShadowLeft/ShadowRight - When placed on the CRT, the window gets a shadow on either the left or right side as well as the bottom. For good human factors, it is recommended that the shadow only be used for the top window for clarity. They are fully supported at any level for serial-access windows. (However, for random-access, the shadows are permitted, but if a window is pulled out from under it, the corners will not be updated at that moment.) Tip: Place windows with shadows correctly to prevent wrap around. ZoomMode - When a window is created, shown, or accessed on the CRT with this mode, it produces a zoom effect. It is conveniently suppressed for hidden windows. RelMode - This is the simplest of all modes. It enables you to set up a window within a window. It simply overwrites the window, but produces a handy window-relative frame of reference to draw borders, write text or whatever. It's a worry-free mode. To get back to the parent window, just use RemoveWindow or switch to another window. RelMode is only temporary and no stats are saved. Let's modify the last example and try this out: EXAMPLE 4: RelMode window ---------------------------------------------------------------------- {$M 16384,8000,8000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,true); SetWindowModes (HiddenMode or ZoomMode or CursorOffMode); MakeWindow (5,20,15,40,White+BlueBG,Cyan+BlueBG,SingleBrdr,Window1); WWriteC (12,'Where is it?'); WriteToHidden (Window1); { Write to the hidden window.} TitleWindow (Bottom,Right,Yellow+BlueBG,' My Second Window '); SetWindowModes (RelMode); MakeWindow (3, 4, 3,32,SameAttr,SameAttr,HdoubleBrdr,aWindow); TitleWindow (Top,Center,SameAttr,' My Answer: '); WWriteC (1,'Here it is ...'); delay (2000); ShowWindow (Window1); { Put it back on the screen. } WWriteC (10,'It was hidden!'); end. Notice that the (Row,Col) location was relative to the parent window, Window1. Even the title as well as the text was placed in RelMode. Once the window was shown, the window coordinates and modes were restored to the parent window. The message appeared correctly on row 10 of the parent window. Notice also that we didn't bother to use RemoveWindow since we were finished and wanted to take a closer look at what we created. PermMode - When creating your initial screen for a program, the underlay probably does not need to be saved. This mode enables you to create windows without saving the underlay so the screen is simply overwritten - perfect for initial screens by increasing speed and saving memory. All the window stats are still saved for future use. Keep in mind two rules for this mode. First, all PermMode windows must be the first ones created. And second, use discretion when accessing the window to make sure it is not Chapter 3, Programming Windows Page 13 WNDW Multi-level Virtual Windows User's Guide, Version 5.X covered by another window before writing to it. Let's try an example: EXAMPLE 5: PermMode window ---------------------------------------------------------------------- {$M 16384,8000,8000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,false); { No need to clear screen } SetWindowModes (PermMode); MakeWindow ( 1, 1,12,80,White+BlueBG,Cyan+BlueBG,SingleBrdr,Window1); TitleWindow (Top,Left,Yellow+BlueBG,' Input Window '); MakeWindow (13, 1,13,80,White+GreenBG,GreenBG,HdoubleBrdr,Window2); TitleWindow (Top,Left,Yellow+GreenBG,' Output Window '); WWrite ( 1, 1,'Output data.'); AccessWindow (Window1); WWrite ( 1, 1,'Input data.'); end. Since we were designing the initial screen, the ClearScr parameter in InitWindow was set to FALSE. Did you notice that writing back to Window1 was no problem? You've just had your first shot at window management! AccessWindow will let you write to any window by name. But if RemoveWindow is used on PermMode windows, the window record is simply dropped from the stack and the screen appears unaltered. SeeThruMode - If there is a portion of the current screen that needs to be captured to become a part of the window itself, this mode creates the border but simply skips clearing contents the window. This is done only when the window is first created. EXAMPLE 6: SeeThruMode window ---------------------------------------------------------------------- {$M 16384,8000,8000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,true); WWriteC (12,'My message'); SetWindowModes (SeeThruMode); MakeWindow (10,26, 5,30,White+BlueBG,Cyan+BlueBG,SingleBrdr,aWindow); TitleWindow (Top,Left,Yellow+BlueBG,' Captured Text '); delay (2000); RemoveWindow; end. When running this program, it appears that a border was just placed over the message "My message". But in fact, it's really a part of the new top window. So, if the window is moved, the contents move as well. HiddenMode - In example 3, we plunged right into making hidden windows and it was easy, too. As it was explained, the hidden window is actually a virtual window in the heap to which you can write at any time. Since virtual screen writing is so very quick, you can even design full screens in an instant and then display them on the CRT. Once a window is shown, it can always be hidden again with HideWindow. This is explained further in Section 5 under Window Management. Chapter 3, Programming Windows Page 14 WNDW Multi-level Virtual Windows User's Guide, Version 5.X VirtualMode - This mode is very simple but powerful and enables you to create a virtual window. A virtual screen is kept in RAM, but we can view any portion of it on the CRT. As you would hope, it's still quite simple: EXAMPLE 7: VirtualMode window ---------------------------------------------------------------------- {$M 16384,8000,8000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,true); SetWindowModes (VirtualMode); MakeWindow (5,20,15,40,White+BlueBG,Cyan+BlueBG,SingleBrdr,Window1); WriteToVirtual (Window1); TitleWindow (Top,Left,Yellow+BlueBG,' Virtual Window '); WWrite ( 1, 1,'Upper left corner'); WWriteC (7,'This message is centered on the screen'); VUpdateWindow; { Update the complete window on the CRT. } WriteToCRT; { Return to writing on the CRT. } end. VUpdateWindow is the workhorse for virtual windows. It copied a portion of the virtual screen, the virtual titles, and the cursor location back on the CRT. You probably noticed that the long message seemed to be cut off. But actually we are only looking at a portion of an 80x25 virtual screen. So the message was indeed centered. You can write direct to the virtual screen and view any portion you want. We have just sampled some of the most powerful features of WNDW with very little effort. Restrictive Modes - NoHideMode, NoAccessMode, and NoMoveMode are modes that restrict window management. These modes are covered in the Window Management section. Back to Defaults - What about getting back to the default modes after they have been changed? Just use SetWindowModes (0). Combinations - Just about any combination of modes can put together. Just sum them together in the SetWindowModes procedure. However, there are some combinations that will not be valid. In fact, the procedure corrects your mistakes. Here's a list of the modes showing invalid combinations: Set Mode Invalid Combination With Correction ------------- --------------------------- ------------------- ShadowLeft ShadowRight ShadowRight ShadowRight ShadowLeft ShadowRight ZoomMode SeeThruMode Ignores ZoomMode RelMode Hidden, Virtual or PermMode RelMode PermMode HiddenMode PermMode RelMode RelMode SeeThruMode ZoomMode Ignores ZoomMode HiddenMode RelMode or PermMode RelMode or PermMode VirtualMode RelMode RelMode Chapter 3, Programming Windows Page 15 WNDW Multi-level Virtual Windows User's Guide, Version 5.X CURSOR MODES Every Window - WNDW fully supports the cursor mode control of QWIK. In fact, every window has its own cursor mode. The setting is controlled by SetCursorDefault. Here's how it works: EXAMPLE 8: Cursor modes in each window ---------------------------------------------------------------------- {$M 16384,8000,8000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,true); MakeWindow (5,20,15,40,White+BlueBG,Cyan+BlueBG,SingleBrdr,Window1); SetCursorDefault (CursorBlock); MakeWindow (9,30,15,40,White+BrownBG,BrownBG,EvenSolidBrdr,Window2); WWrite ( 1, 1,'Upper left corner'); GotoEos; delay (2000); RemoveWindow; delay (2000); RemoveWindow; end. When you ran this code, you noticed that top window had a block cursor. When the window was removed, the cursor mode was restored to new top window as an underline. Just like SetWindowModes, the value is saved in CursorDefault until changed. Initial Window - InitWindow sets CursorDefault to the current cursor mode which is used for all subsequent windows and Window0. If you even want Window0 to have a different cursor mode and default, simply use Qwik.SetCursor before InitWindow. CursorOffMode - So, what's the difference between using CursorOffMode and using SetCursorDefault (CursorOff)? For technical reasons, in virtual windows, the cursor could be turned on and off. If the setting of CursorOff is used, then the cursor could be turned on having an overbar cursor ($0000). It's easier to use CursorOffMode. Chapter 3, Programming Windows Page 16 WNDW Multi-level Virtual Windows User's Guide, Version 5.X 3. W R I T I N G T O W I N D O W S WNDW has several window-relative routines designed to write in the windows, including direct writing, cursor and EOS positioning, clearing, scrolling, and line drawing. They work in all types of windows, including hidden and virtual. To do this, the routines access the top window record (TWS or TopWndwStat) that keeps information about the current window. For a breakdown on the window record, see Data Structure in WNDWREF.DOC. Each of these groups of routines are discussed below. DIRECT WRITING Window Relative - Rather than using Qwrite to write to windows, three routines are provided to use window-relative coordinates. You have already used two of them. The attribute used is the window attribute TWS.WndwAttr. WWrite (Row,Col: byte; aStr: string) WWriteC (Row: byte; aStr: string) WWriteA (Row,Col: byte; ArrayLength: word; VAR aStr) WWriteC centers the string within the window while WWriteA is for arrays or substrings. These routines are actually externals that interface the QWIK routines using TWS. QWIK Support - You will be pleased to know that QWIK is fully integrated and supported in WNDW like your favorite use of SameAttr and the EOS marker. Wherever an attribute is needed, SameAttr can be used. And all the window-relative writing routines support the EOS. For example, to chain after a WWrite statement, just do the following: WWrite (1,2,'My message'); QwriteEos (SameAttr,' is here'); This would write the message "My message is here" on window-relative row 1, column 2, also indicated as (1,2), with the current window attribute. Changing Attributes - Suppose you do not want to use the current window attribute. How can it be altered? The QwriteEos example above is one way. But since the original window attribute is saved in TWS.OrigAttr, it can be temporarily be changed by doing the following: with TWS do begin WndwAttr := NewAttr; { Assign new attribute } WWrite (1,1,'New Attribute'); WndwAttr := OrigAttr; { Restore window attribute } end; CURSOR AND EOS POSITIONING WNDW has eight routines to locate and move either the cursor or the EOS marker relative to the current window. Chapter 3, Programming Windows Page 17 WNDW Multi-level Virtual Windows User's Guide, Version 5.X Cursor Location - Just like WhereR/WhereC, the following functions return the current cursor location: WWhereR - Window-relative row. WWhereC - Window-relative column. Cursor Movement - Similar to GotoRC and GotoEos, the following procedures move the cursor: WGotoRC - Move to window-relative row and column. WGotoEos - Move cursor to match EOS marker location. So, what's the difference between GotoEos and WGotoEos? The latter does two more operations - (1) the cursor location is saved in TWS, and (2) the cursor mode is tested in virtual windows to be turned on or off. To be consistent in windows, it is easier to use WGotoEos. EOS Location - Similar to EosR and EosC, the following functions return the current EOS location: WEosR - Window-relative row. WEosC - Window-relative column. EOS Movement - Similar to EosToRC and QEosLn, the following procedures move the EOS marker: WEosToRC - Move EOS to window-relative row and column. WEosLn - Move EOS to column 1 of the next row with a possible scroll if past the last window row. CLEARING WNDW provides seven window-relative routines for clearing portions of the window including lines, titles, fields, and even the full window with the window attribute TWS.WndwAttr. SameAttr becomes very handy when complex attribute fields have already been designed into the window. WClrScr - Clears entire window. WClrTitle - Clears entire title given Top or Bottom. WClrLine - Clears an entire row. WClrEol - Clears a row to End-Of-Line given a (Row,Col). WClrEos - Clears a row from EOS to EOL. WClrField - Clears a field given a (Row,Col). WClrFieldEos - Clears a field at EOS. Each of these procedure places the EOS marker at the beginning of the cleared area for convenient chaining. (WClrTitle does not alter EOS.) The latter four procedures also provide an optional attribute change. Here are some examples with a variety of ways to enter data using many of the above window-relative routines: Chapter 3, Programming Windows Page 18 WNDW Multi-level Virtual Windows User's Guide, Version 5.X EXAMPLE 9: Window-relative writing routines ---------------------------------------------------------------------- {$M 16384,8000,8000 } uses Crt,Qwik,Strs,Wndw,Goof; var s1,s2,s3: string; r1,r2: real; Ch: char; begin InitWindow (LightGrayBG,true); MakeWindow (5,20,15,40,White+BlueBG,Cyan+BlueBG,SingleBrdr,Window1); s1 := ' a:\long\long\filename'; s2 := ' a:\shorter\filename'; s3 := ' error message'; r1 := 1.0; r2 := 14.33e3; WWrite ( 2, 2,'File name: '); WClrEos (LightGrayBG); { Clear first field } QwriteEos (SameAttr,s1); { Put in file name } WWrite ( 3, 2,'Status'); WClrField ( 3,13,20,LightGrayBG); { Clear second field } QwriteEos (SameAttr,s3); { Put in status message } WWrite ( 4, 2,'Quantity: '); WClrFieldEos (20,LightGrayBG); { Clear third field } QwriteEos (SameAttr,StrRFD(r1,19,1)); { Put in formatted data } EosToRCrel (0,-1); { Shift EOS back one space } WGotoEos; TitleWindow (Bottom,Center,Yellow+BlueBG+Blink,' Press any key '); repeat Ch := ReadKey; until Ch<>#00; WClrTitle (Bottom); TWS.WndwAttr := SameAttr; { Keeps field attributes intact } WWrite ( 2,13,s2); WClrEos (SameAttr); { Clears remainder of long filename } WClrEol ( 3,13,SameAttr); { Clears beyond field, But A OK! } WWrite ( 4,13,StrRFD(r2,19,1)); { Overwrites new data } TWS.WndwAttr := TWS.OrigAttr; { Restore window attribute } end. When running this example, the window will display the formatted data in their fields. Then press a key as requested. Then the fields are updated with new data. Notice that the fields are only overwritten and not cleared first. This produces the best human factors by appearing flawless. SCROLLING Some operations may require scrolling all or just portions of a window. WNDW has four routines to do this, and, like all other WNDW routines, they operate in all windows and video pages at the highest speed without flicker or snow. Full Window - To scroll the entire window, two routines scroll the window up or down. You may also want to consider the conditional scroll of Chapter 3, Programming Windows Page 19 WNDW Multi-level Virtual Windows User's Guide, Version 5.X WEosLn: WScrollUp - Scrolls window up. WScrollDown - Scrolls window down. Partial Window - Just like InsLine and DelLine, these two routines insert and delete lines by specifying the row. WDelLine - Deletes the specified row scrolling the remainder up. WInsLine - Inserts the specified row scrolling the remainder down. LINE DRAWING The border alone is not sufficient for the design of many windows that need to be partitioned in a logical manner. WNDW has six procedures to completely partition any window - three are for extending the border and three are for a separate line drawing set for the inside window. Border Drawing - The following procedures can easily add an extra partition to the window by using the current border style (TWS.WSbrdr) and the border attribute (TWS.BrdrAttr): WBrdrH - draws a horizontal partition at the given row complete with tees. WBrdrV - draws a vertical partition at the given columns complete with tees. WBrdrPart - places a single border part at the given row and column usually used for a cross or tee. Line Drawing - When a window is created, the line drawing set (TWS.WSline) is the same as the border style (TWS.WSbrdr) but can freely be changed. The following procedures can easily add an extra line within the window by using the line drawing set and the current window attribute (TWS.WndwAttr): WLineH - draws just a horizontal line at the given (Row,Col) repeated for a number of columns. WLineV - draws just a vertical line at the given (Row,Col) repeated for a number of columns. WLinePart - places a single line part at the given row and column usually used for a cross or tee. Acronyms - To make it easy to remember each individual part of a border or line set, each part has its own acronym. For example, BrdrTL means the Top Left border part. Here are the parts in their relative positions and their definitions: Relative Position The first letter of the border acronym mean: ------------------ T = top B = bottom TL TH TT TH TR V = vertical H = horizontal LV VL RV L = left R = right LT HL CL HL RT C = cross LV VL RV The second letter is the same except for: BL BH BT BH BR T = tee L = line Chapter 3, Programming Windows Page 20 WNDW Multi-level Virtual Windows User's Guide, Version 5.X Example - Let's see if we can try some screen design with these routines with this example: EXAMPLE 10: Screen design ---------------------------------------------------------------------- {$M 16384,8000,8000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,true); MakeWindow ( 5,19,17,41,GreenBG,White+GreenBG,VdoubleBrdr,Window1); TWS.WSline := SingleBrdr; { Don't want VdoubleBrdr } WLineH ( 4, 1,TWS.Wcols); { Use Wcols for full window width } WLineH (12, 1,TWS.Wcols); WBrdrH (8); WBrdrV (20); WBrdrPart ( 8,20,BrdrCL); { For the Cross Line } end. When you see this executed, it is apparent that the borders are connected with tees. Notice that the line set uses the window attribute. I'll bet you didn't know screen design could be this easy! Why use compressed screens? CUSTOM ROUTINES You can make your own custom routines to be window-relative by using the current window record. This topic will get you familiar with the window coordinates and guide you through an example. Coordinates - The top window record has two sets of coordinates - one set includes the border and the other excludes it. Here are the field identifiers for the ones including the border: WSrow - Row of the top border. WScol - Column of the left border. WSrows - Number of rows from border to border. WScols - Number of columns from border to border. WSrow2 - Row of the bottom border. WScol2 - Column of the right border. The "WS" acronym means WndwStat which was used to create the window. But usually you would want the coordinate for the text window exclusive of the border ("W" acronym) and here are those field identifiers: Wrow - Top row of the window. Wcol - Left column of the window. Wrows - Number of rows in the window. Wcols - Number of columns in the window. Wrow2 - Bottom row of the window. Wcol2 - Right column of the window. For example, to access the top row of the window, use TWS.Wrow. This uses the same amount of code as a simple variable. Chapter 3, Programming Windows Page 21 WNDW Multi-level Virtual Windows User's Guide, Version 5.X Example - You may have noticed that there is no Wfill procedure included in WNDW. That's because it's so simple to customize your own. Let's try to write one: procedure Wfill (Row,Col,Rows,Cols: byte; Ch: char); begin with TWS do Qfill (pred(Wrow+Row),pred(Wcol+Col),Rows,Cols,WndwAttr,Ch); end. You can do the same to all your routines and they can work in any displayed or hidden window, or even virtual screens. Chapter 3, Programming Windows Page 22 WNDW Multi-level Virtual Windows User's Guide, Version 5.X 4. V I R T U A L W I N D O W S Now that you have a good idea of what windows can do, virtual windows will add a greater magnitude of power and flexibility to your windows with no more effort than what has already been covered. This section shows the practical applications and how to program them. APPLICATION This topic will help you decide when virtual windows can meet the needs of your programming application. More Power - The default mode for making windows is a fixed-size window with all of the text displayed. But what if you want variable sized windows or want to write to windows that are not displayed or even covered? Virtual windows to the rescue! They handle this automatically. Definition - What is a virtual window anyway? There are two parts to a virtual window - the screen and the view. The screen part is written in RAM while the view is seen on the CRT. So, we can write to the screen at any time and show only a portion to the CRT as required! Advantages - Since QWIK has already developed low-level tools for virtual screens, WNDW uses them to create quick virtual windows. Here's the advantages: . Variable row-by-column screen size up to 64k. . Extremely high speed in RAM. . Number of screens only limited by memory. . Can update windows even if they are overlapped, covered, or hidden. . The view can be resized without losing text. . The screen allows wraparound. . Can access any screen at any time. If your application has operations in one window that affects others, then virtual windows are essential. An example of this is the Turbo Debugger environment where operations in the CPU window affect items in the source code and watch windows. PROGRAMMING Remember, we already did some virtual window programming back in Example 7 and there wasn't anything to it. Now, in this section, you will learn additionally how to make, write, update, view, and resize a virtual window. Compiling - To include the virtual window code in the unit, the conditional directive AddVirtual must be defined. The distributed unit already has defined it for you. If you have the source code, the directive is found at the top of WNDW5X.PAS. To eliminate the code when virtual windows are not needed, simply remove the "$" in front of "Define AddVirtual". Creating - All we have to do to make a virtual window is use VirtualMode Chapter 4, Virtual Windows Page 23 WNDW Multi-level Virtual Windows User's Guide, Version 5.X in the SetWindowModes procedure. The default size for screen is the current screen dimensions as set by InitWindow. But suppose a different size is needed. How can that be changed? SetVirtualSize controls the screen size. Here's an example: EXAMPLE 11: Virtual window sizing ---------------------------------------------------------------------- {$M 16384,10000,10000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,true); SetWindowModes (VirtualMode); SetVirtualSize (20,100); { 20 rows by 100 columns } MakeWindow (5,20,15,40,LightCyan+BlueBG,White+BlueBG,SingleBrdr, Window1); WriteToVirtual (Window1); { Now write to the virtual screen } Qfill (1,1,CRTrows,CRTcols,SameAttr,'?'); { Fill screen with data } TitleWindow (Top,Left,Yellow+BlueBG,' Virtual Window '); WWrite ( 4, 8,' >'); { Let's get our bearings. } QwriteEos (TWS.WndwAttr+blink,'+'); QwriteEos (SameAttr,'<- Row 4, Column 10 '); VUpdateWindow; { Update the complete window on the CRT. } delay (2000); { Make sure we see where the cursor is. } RemoveWindow; end. Notice that we chose a 20x100 screen, but what is seen on the CRT is only 15x40 which is set by MakeWindow. So, MakeWindow sets the view size while SetVirtualSize sets the screen size. Writing to the Screen - Since there are two areas to write on a virtual window, the view and the screen, WNDW must be told where you intend to place text. Right after this MakeWindow procedure, it is assumed we are going to continue to write on the CRT. But the primary place to write is the virtual screen. WriteToVirtual selects that screen. All subsequent procedures will write to it - all QWIK routines, WNDW routines, and even TitleWindow and MakeWindow. It is treated just like any other screen. The exception of course is the cursor routines which must be handled by WNDW routines only. RelMode - If you do write to the virtual screen and use MakeWindow, the mode is forced into RelMode. Otherwise, the window would be nested and WNDW could not support it. Memory - What does the screen actually look like in memory? It is saved in the heap in the same way as a CRT video screen. Technically, the far pointer QScrPtr points to the location of the screen which is a contiguous array of Character/Attribute words. The last two rows past the screen are reserved for the virtual titles which are seen on the CRT view when updated. Writing to the View - It is possible to write to the view if desired. To get back and write to the top view, use WriteToCRT. But the next time the window is updated, it will all be lost. Chapter 4, Virtual Windows Page 24 WNDW Multi-level Virtual Windows User's Guide, Version 5.X Updating - At some time, we would probably like to see the screen and we can do this with any of five updating procedures. The main workhorse is VUpdateWindow which has been demonstrated several times. This procedure is so carefree is doesn't even matter when you use it. It updates the virtual window of the current name (TWS.WSname) no matter where it is - on top, covered, overlayed, and even hidden from the CRT! The routine actually hunts for it and updates it. To show how it can do this, let's modify the last example: EXAMPLE 12: Updating covered windows automatically ---------------------------------------------------------------------- {$M 16384,12000,12000 } uses Crt,Qwik,Wndw,Goof; begin InitWindow (LightGrayBG,true); SetWindowModes (VirtualMode); SetVirtualSize (20,100); { 20 rows by 100 columns } MakeWindow (5,20,15,40,LightCyan+BlueBG,White+BlueBG,SingleBrdr, Window1); SetWindowModes (0); { Back to default modes. } MakeWindow (7,30,16,18,White+GreenBG,GreenBG,DoubleBrdr,Window2); delay (2000); { Make sure we see where the cursor is. } WriteToVirtual (Window1); { Now write to the virtual screen } Qfill (1,1,CRTrows,CRTcols,SameAttr,'?'); { Fill screen with data } TitleWindow (Top,Left,Yellow+BlueBG,' Virtual Window '); WWrite ( 4, 8,' >'); { Let's get our bearings. } QwriteEos (TWS.WndwAttr+blink,'+'); QwriteEos (SameAttr,'<- Row 4, Column 10 '); VViewRC (4,10); VUpdateWindow; { Update the complete window on the CRT. } delay (1000); RemoveWindow; delay (2000); { Make sure we see where the cursor is. } RemoveWindow; end. With the delay inserted, it gives you time to clearly see that the covered virtual window was updated even though it was covered by another window. But that's not all. When the window was removed, you could see that it was fully updated even under the part that was covered! That's the power of virtual windows. Updating Routines - There are four other updating procedures that can be chosen other than VUpdateWindow: VUpdateView - Updates just the window contents. VUpdateTitles - Updates just the titles. VUpdateCursor - Updates new cursor position. VUpdateRows - Updates selected rows on top view, but full view if covered. VUpdateWindow actually executes the first three. But they are also available as separate routines for more detailed work. When the view is on top of the CRT or hidden, the routines are extremely quick. VUpdateRows is especially quick for items like data entry to the virtual screen. If the Chapter 4, Virtual Windows Page 25 WNDW Multi-level Virtual Windows User's Guide, Version 5.X windows are covered, the procedures have to do more work. Then VUpdateWindow takes about the same time as either VUpdateTitles and VUpdateView, so VUpdateWindow might as well be used. VUpdateCursor is almost a trivial routine in any case. Viewing - In this example, you may have noticed that the view was shifted a bit compared to Example 11, and that the cursor was no longer in view. It was shifted by the viewing routine VViewRC. In fact, we could view any part of the screen. Three routines can adjust the reference point of view of the upper left corner: VViewRC - Changes to a given (Row,Col). VViewRCrel - Shifts a number of rows and columns, positive or negative. VScrollView - Shifts a number of rows and columns, and updates the just the view and accepts mouse stepped input. The first two only change the coordinates in the virtual window record, while VScrollView updates the view as well. VViewRCrel is actually a subroutine of VScrollView. All routines check for bounds and will keep the view within screen limits. Resizing - If the virtual window is the top view, two routines can resize it by shifting the lower right hand border: VResizeWindow - Shifts a number of rows and columns, and updates the entire window. Accepts both row and column parameters which permit mouse stepped input. VZoomWindow - Toggles window between full size and current size. Zooming up, the window is centered on the screen and the view is at (1,1). Zooming down, it returns to the same size and location, but the view remains at (1,1). Both routines force writing to the CRT upon exit. They also completely update the window since the view and cursor may be shifted. The titles are also smoothly updated. The zoom can be toggled back and forth as long as it hasn't changed size or hasn't zoomed up another window. Chapter 4, Virtual Windows Page 26 WNDW Multi-level Virtual Windows User's Guide, Version 5.X 5. W I N D O W M A N A G E M E N T Some of the previous examples have already touched on the principles of window management. Now this section provides the full scope of management to access windows for display or writing, including multiple video pages. ACCESS METHODS The are two basic methods for accessing windows: serial access and random access; WNDW does them both. Serial Access - This is a simple method of stacking windows over each other and then removing them in reverse order. Any writing is always done on the top window displayed on the CRT. The only two procedures used are MakeWindow and RemoveWindow. For simple menu systems, serial access may be all that is needed. The advantages are: . Uses less code. . No gaps in heap memory. . Only one place to write. But the disadvantages are many. Once a window is removed, it is lost from memory and must be recreated. This can cause a significant amount of shuffle to access other windows. Serial access is a subset of random access. Random Access - More and more applications require access to any window at any time without losing the data. WNDW was designed to handle this automatically at very high speed. The advantages to random access are: . Free access to any window. . Windows are created only once. . Virtual windows can be updated even if covered. . Ease of programming. Any window can be randomly accessed, including fixed, virtual and hidden windows. It's as simple as that. Try running the window management demo WNDWMGR.PAS again and see how you can hide, show, and access any window. The instructions are on the screen. DISPLAY CONTROL Three procedures select the window to be displayed as the top window: AccessWindow - Accesses the window by name whether hidden or covered. HideWindow - Hides the top window. ShowWindow - Shows a window given its name. AccessWindow hunts for the named window and, if it is hidden, it will also be shown. ShowWindow is actually a subroutine of AccessWindow. Any window (except PermMode) can be hidden and shown; they do not have to be created with HiddenMode which hides it at the start. Chapter 5, Window Management Page 27 WNDW Multi-level Virtual Windows User's Guide, Version 5.X EOS - When using Hide/ShowWindow, the EOS is reset to (1,1) to prevent unexpected results. However, if the window is currently displayed on the CRT and AccessWindow is used, the EOS is restored to its previous value. RemoveWindow - This procedure could be considered a form of display control, but remember that when a window is removed, it is gone forever, including any virtual screen. MoveWindow - This procedure shifts the top window around on the CRT by a given number of rows and columns allowing mouse stepped control. A window can be limited in movement by setting the margins in MarginRec. The bounds are conveniently checked, so the window will always stay within limits. In the WNDWMGR.PAS demo, you can see the status line on row 25 is never overlapped by MoveWindow. Although Window0 is a permanent one, we could easily write to the status line at anytime by using AccessWindow (Window0). Changing Borders - For human factors, it is often helpful to have a border be emphasized when it becomes the new top window. Two high speed procedures handle this well: ChangeBorder - Changes the top window to the new given border style. RestoreBorder - Restores the original border created with MakeWindow. Both of these procedures work only on the top window, and they can either be fixed or virtual. They replace all border parts including tees and also leave all titles untouched. WRITE CONTROL Three procedures select where the writing procedures will write: WriteToHidden - Writes to the named hidden window. WriteToVirtual - Writes to the named virtual screen. WriteToCRT - Writes to the current top window on the CRT. WriteToHidden - A hidden window is saved with the border intact, but is stripped of any shadow. It is easier to use the window-relative writing routines because of the optional border rather that using QWIK which can still be used. Any shadow is reconstructed by ShowWindow. WriteToVirtual - A virtual screen can freely use either WNDW or QWIK routines since it never has a border. If you want to write directly to the virtual screen after it has just been created, sometimes it's easier to use WriteToVirtual (TWS.WSname) provided HiddenMode was not used as well. WriteToCRT - All routines continue to write to their destination until changed. This routine will get you back to writing on the CRT. Some procedures are forced back to the CRT after their operation. Here are those exceptions: AccessWindow VResizeWindow MoveWindow HideWindow VZoomWindow ShowWindow ChangeBorder RemoveWindow RestoreBorder Chapter 5, Window Management Page 28 WNDW Multi-level Virtual Windows User's Guide, Version 5.X REMEMBER: Use WriteToCRT to get back to the CRT. If you forget, the text will of course be in an unexpected window. MakeWindow - This procedure does NOT force a change in the write destination. If you are writing to a hidden window or a virtual screen, the resulting window created by MakeWindow is forced into RelMode. However, the WindowModes setting is not affected. WINDOW MODES AND FLAGS Additional window modes are available to restrict window operations or to detect the window destination status. Each mode has a corresponding boolean flag. Restrictive Modes - In some applications, you may want to restrict what the end user can change for the windows. Before the window is created with MakeWindow, use these modes in SetWindowModes. The flag can be used for testing. Set Mode Set Flag Description ------------ ------------ -------------------------------------------- NoHideMode NoHideFlag Ignores HideWindow operation. NoAccessMode NoAccessFlag Ignores AccessWindow operation. NoMoveMode NoMoveFlag Ignores MoveWindow/VResizeWindow operations. Destination Modes - These modes are just for your information and are handled automatically by WNDW. These identify the write destination of the window. You can use the flags for testing, but the modes are ignored by SetWindowModes: Set Mode Set Flag Description ------------- ------------- ------------------------------ ToCRTMode ToCRTFlag Writing to the CRT. ToHiddenMode ToHiddenFlag Writing to the hidden window. ToVirtualMode ToVirtualFlag Writing to the virtual screen. HIGH SPEED SCREEN DESIGN By using Hidden or Virtual windows, WNDW enables you to make screen design several magnitudes faster than you ever thought possible. Comparing Speeds - Let's compare three speeds - (1) Turbo's direct video, (2) QWIK/WNDW writing to CRT, and (3) QWIK/WNDW writing to RAM. The following chart is striking. ---- QWIK/WNDW ---- Video Card Turbo To CRT To RAM ---------- ----- ------ ---------- CGA 100% 225% 1600-4100% All others 100% 750% 900-1700% Chapter 5, Window Management Page 29 WNDW Multi-level Virtual Windows User's Guide, Version 5.X Design Strategy - So how can you get these fantastic speeds? The simplest way was shown in Example 3 by creating hidden windows. You may wish to make a habit of creating your windows with HiddenMode and then immediately show them with ShowWindow. Virtual window code is not even required for hidden windows. Of course, the alternative is to go ahead and use virtual windows. Either way, you can actually see the increase in performance in your programs. Code Savings - Many application programs use disk-based screens that are called from the disk when required. QWIK and WNDW require such little code to create a full screen design, that you will actually save code and disk space by using these routines - not to mention the increase in speed! MULTIPLE VIDEO PAGES Most color video cards have the capacity for multiple video pages. If your application can benefit with extra pages, WNDW handles all the data records with simplicity. Compiling - To include the multiple video page code in the unit, the conditional directive MultiPage must be defined. The distributed unit already defines it for you. If you have the source code, the directive is found at the top of WNDW5X.PAS. To eliminate the code when these pages are not needed, simply remove the "$" in front of "Define MultiPage". Changing Pages - To change video pages, use one of the following procedures: WriteToPage - Directs all QWIK and WNDW routines to write to the given page number, but still view the current page. WriteAndViewPage - Directs all QWIK and WNDW routines to write and to view the given page number. Separate Records - Each video page has its own set of window records that are completely separate including the level indexes and top window stats. So when pages are swapped, everything is just where it was left - even the cursor mode and EOS. However, the virtual screen records use the same array in the heap, but, to keep them separate, they do not share records. Chapter 5, Window Management Page 30 WNDW Multi-level Virtual Windows User's Guide, Version 5.X 6. D A T A M A N A G E M E N T Almost all of the data is handled automatically by WNDW. This section is provided for those who are interested in the details of data management and the inner workings of WNDW. The only required reading is Data Allocation. Otherwise, you can skip this section. DATA ALLOCATION This topic will provide you enough knowledge to budget the number of data records needed for you program using the constants MaxWndw, MaxVirualWndw, and MaxPageUsed. Data Structure - For a detailed description of the data structure, you can refer to Data Structure in Section 3 of WNDWREF.DOC. To be able to adjust the data structure, you must have the source code. If not, the sizes have been preassigned. MaxWndw - Each window on the CRT, displayed or hidden, requires one window record of statistics called WndwStat which is global data. The initial window, Window0, is always at WndwStat[0]. They array of records is sized by MaxWndw as the highest number of windows, hidden and displayed, that are on the CRT at any one time on any one video page. For example, if page 0 has a maximum of 10 windows and page 1 has 6, set MaxWndw equal to 10. MaxVirtualWndw - Each virtual window has two window records - one is in WndwStat for the view and the other is in VirtualStat for the virtual screen which is dynamic data. The first virtual screen is saved in VirtualStat[0] since it is zero based. The array of records is sized by MaxVirtualWndw as the highest total number of active virtual windows. For example, if page 0 has 4 virtual windows and page 1 also has 4, set MaxVirtualWndw equal to 7 (not 8). MaxPageUsed - This is the highest page number that will be used in a multiple video page program. If you are only using page 0, which is usually the case, you should go ahead and undefine the directive MultiPage and not bother with MaxPageUsed. Each page saves its own WndwStats and Indexes in one record called PageStat in an array in dynamic memory. MaxPageUsed and Qwik.MaxPage are compared and the lesser of the two will size the PageStat array. Program Development - When you first start developing a program, make it easy on yourself and inflate these constants to provide enough freedom without having to recompile. In your final program, you can trim them down and retest. RECORD HANDLING If you are wondering where your WndwStat record is being saved, the following will show you how it is managed. Chapter 6, Data Mangement Page 31 WNDW Multi-level Virtual Windows User's Guide, Version 5.X Displayed Stack - Each window as it is displayed on the CRT has its corresponding window record saved in WndwStat starting from the bottom of the array and stacked upward. The base window, Window0, is permanent and saved in WndwStat[0]. The first window displayed is saved in WndwStat[1], the second in WndwStat[2], and so on. The top window is in WndwStat[LI] where LI is the top Level Index. Hidden Stack - Hidden windows have their record moved from WndwStat[LI] to the top of WndwStat starting from the top of the array stacked downward. As you can imagine, the hidden stack is simply inverted to the displayed stack. So, when a window is hidden, it is placed starting at WndwStat[MaxWndw]. The last hidden window saved is at WndwStat[HLI]. HLI is the Hidden Level Index. Conversely, when a window is shown, it is removed from the hidden stack and replaced in WndwStat[LI]. Random Access - Anytime a window is randomly accessed, the record is pulled out from the middle of the stack. The stack is then dropped to fill the gap. VirtualStat - The records for the virtual screens are kept in dynamic memory in an array called VirtualStat and are not shuffled like the window records. If a window is virtual, the index to the virtual screen is WndwStat[?].VI. TopWndwStat - The current window stats are always maintained in the global record TopWndwStat (TWS). Combined with a WITH statement, the code is optimized just like simple global variables. When working with the current window, always use TopWndwStat (TWS) in lieu of WndwStat or VirtualStat. TopVirtualStat - Just like TWS, a copy of the current virtual screen record from VirtualStat is maintained in the global record TopVirtualStat (TVS). RelMode Records - RelMode windows only have the record temporarily placed in TWS and are not saved in the stack. They are overwritten with any change of windows. PermMode Records - PermMode windows have a copy of its record placed in TWS (and TVS if virtual), but the stack is not shuffled and there are no gaps. All PermMode records must be the first ones in the stack. The highest index of permanent windows is maintained in PLI the Permanent Level Index. Saving Records - Again, WNDW handles this automatically, TWS and TVS are saved in their appropriate WndwStat or VirtualStat. Remember, when writing to virtual screens, TWS and TVS are reversed. It may be helpful to think of TVS then as the Top View Stat on the CRT. Finding Records - Since the records are shuffled, just how do you find the record you want? Given the window name, GetLevelIndex returns the index in WndwStat for the window record. Page Records - When swapping pages, WNDW swaps the entire WndwStat array, top window records, indexes, margins, cursor mode and window modes for each page. Heap - Virtual screens and hidden windows are saved in the heap. To Chapter 6, Data Mangement Page 32 WNDW Multi-level Virtual Windows User's Guide, Version 5.X figure your heap requirement, please refer to Appendix A in WNDWREF.DOC. For your own program, you can also use the HeapOK procedure to test for MaxAvail. If there is insufficient heap space, then HeapOK will terminate the program through the GOOF unit. Stack - Stack checking has been turned off in the units. Less than 2k is used for any procedure. Chapter 6, Data Mangement Page 33 WNDW Multi-level Virtual Windows User's Guide, Version 5.X 7. U T I L I T Y U N I T S Two other units are required with the WNDW package - GOOF and WUTIL. The GOOF unit handles programming errors while WUTIL has some high speed screamin' routines to add zing into many of the window operations. WUTIL is already compiled into WNDW, but the unit is available for your other programs as well. GOOF UNIT All programmers make mistakes, right? So, what happens when you try to make more windows than there are records available? Since WNDW is so powerful and can even write in RAM, there is a good possibility that your mistake may not even show up on the screen. How do you know if anything has gone wrong? The GOOF unit was made especially for handling errors. Displaying Errors - When an error is found in your program, the ShowGoof procedure is called and the program is terminated. The CRT will display an error message in a flashing window. There are eight fatal errors that are listed in APPENDIX B in WNDWREF.DOC to identify problems before they happen. Please refer to it for the error messages and their solutions. Flexibility - ShowGoof is accessed indirectly with an indirect call. This means that you can freely edit the GOOF unit without needing to recompile WNDW. You can even edit it for use in your own applications. The error message numbers 1-50 are reserved. So, for your own applications, it is suggested that you start with number 51. If you have thoroughly tested your program, some of the messages can be eliminated. Using GOOF - It is very important that GOOF be included in the USES list. You may find that it compiles without it, but if an error does occur, your system will surely crash. Notice that GOOF is the last unit in the USES list as it uses both QWIK and WNDW. WUTIL UNIT To help make WNDW into a fast unit, some maximum/minimum functions and move procedures were included in the separate unit WUTIL. Since WUTIL is an independent unit, you can also use it by itself in your own programs. Maximum/Minimum - These high speed functions compare two values and return the result whether maximum or minimum. They have been trimmed down to operate on specific data types and only use 112 bytes total. MaxI - returns the maximum of two integers. MaxL - returns the maximum of two long integers. MaxW - returns the maximum of two words. MinI - returns the minimum of two integers. MinL - returns the minimum of two long integers. MinW - returns the minimum of two words. Chapter 7, Utility Units Page 34 WNDW Multi-level Virtual Windows User's Guide, Version 5.X Move16/MoveWords - Since WNDW needs the highest speed move procedures, two routines were developed. Move16 - Drop-in replacement for TP's Move that is twice as fast using 16-bit transfers. MoveWords - Faster than Move16, but destination cannot overlap Source[0]. Chapter 7, Utility Units Page 35 WNDW Multi-level Virtual Windows User's Guide, Version 5.X A P P E N D I X A : A P P L I C A T I O N P R O D U C T S | Eagle Performance Software has developed identical products for both | Turbo C and Turbo Pascal. Our pledge is to provide you quality products | with unparalleled performance and ease of use. All registered users | receive the complete source code when a signed license agreement is | returned. QWIK QWIK - For direct screen video, QWIK is the highest performance screen writing tools available today for all text modes in any video configuration. QWIK provides capabilities far beyond in the unit/library that comes with your compiler. Here are some of the features: - Writes on all IBM compatible computers, displays and adapters including MDA, CGA, EGA, MCGA, VGA, 8514/A, Hercules and 3270 PC. - Superior video detection routine. - Eliminates snow and flicker. - Writes directly to the screen in absolute rather than relative coordinates. - Writes in all text modes and column modes. - Writes on all video pages. - Writes on virtual screens in RAM. - Writes text and attribute, text only, or attribute only. - Reads strings, characters and attributes. - Uses End-Of-String (EOS) marker for quick string chaining. - Provides standardized cursor shapes for all adapters. - Enhanced cursor movement. - Compatible with DESQview and similar multitasking environments. - Over 650% faster than standard direct screen writing. - Only 2.7k bytes of code if all 43 utilities are used. - Optimized by the compiler and drops unused code. - Used in all other Eagle products. - Excellent documentation like this document. Here are the product versions: File name CIS Name Compiler Release date ----------- ---------- -------- ------------ QWIK42B.ARC QWIK42.ARC TP4 10-01-88 QWIK5X.ARC QWIK5X.ARC TP5 12-20-88 QWIKC20.ARC QWKC20.ARC TC2 12-03-88 WNDW - Here are the current product versions of WNDW: File name CIS Name Compiler Release date ----------- ---------- -------- ------------ WNDW42.ARC WNDW42.ARC TP4 10-15-88 WNDW5X.ARC WNDW5X.ARC TP5 10-15-88 WNDWC20.ARC WNDC20.ARC TC2 02-01-89 Appendix A: Application Products Page 36 WNDW Multi-level Virtual Windows User's Guide, Version 5.X PULL PULL - For multi-level pull-down menus, PULL is fully featured and fully configurable. Includes execute, single, and multiple choice menus, unlimited nested submenus, data entry windows, help windows, directory windows, message system, and fully completed interfaces. Some of the features are: - Uses QWIK and WNDW. - Work window(s) and complete interface for menus - Pull-down menus with 3 menu modes and 7 line modes - Pull-down file directory - Highlighted command letters - Unlimited levels of submenus - Unlimited data entry windows for 9 types of data - Data entry for the work window(s) Free field entry with either fixed column or flexible column length. Full editing capability including insert cursor mode Full field selection with cursor keys Automatic NumLock for numerical data entry Right or left justification for data entry output Error messages for invalid data entries Error messages for data entries out of range - Automatic sizes and locations for menus. - Operation by cursor keys or command keys - Pull/Pop between work window and nested submenu(s) - Programmable control of pull and pop sequences - Context-sensitive help - Message lines for prompts and processing - Full working shell for user development - Excellent documentation like this document. Here are the product versions: File name CIS Name Compiler Release date ----------- ---------- -------- ------------ PULL42.ARC PULL42.ARC TP4 01-03-89 PULL5X.ARC PULL5X.ARC TP5 TBA PULLC20.ARC PULC20.ARC TC2 TBA ON-LINE SERVICES CompuServe - All updated files and later versions can be found on the CompuServe Borland Forums (GO BPROGA for TP and GO BPROGB for TC) or the IBM Programming Forum (GO IBMPRO). | The Eagle BBS - After 01-10-89, you can also get the latest files on our | 24-hour BBS at (214) 539-9878, 300/1200 N81. Appendix A: Application Products Page 37 WNDW Multi-level Virtual Windows User's Guide, Version 5.X A P P E N D I X B : R E V I S I O N H I S T O R Y REVISIONS: Version 4.0 (12-12-87): . Incorporated QWIK40.TPU for full IBM compatibility. . Combined all modes into one variable - WindowModes. . Added the following procedures/functions: SetWindowModes RestoreTurboWindow PartitionWindow PartitionCross ClearTitle ClearWindow HideWindow ShowWindow MoveWindow AccessWindow GetLevelIndex . Added 7 background constants. . MakeWindow now requires a WindowName. . TitleWindow requires one more direction parameter. . Current WndwStats are kept in TopWndwStat rather than WndwStat[LI]. . LIcurrent was deleted. . Changed BrdrRec type for easier modifications. . Added 3 more borders - VdoubleBrdr, ThinSolidBrdr2, UserBrdr2. . Changed the following names: MixedBrdr to HdoubleBrdr ThinSolidBrdr to ThinSolidBrdr1 Tattr to TextAttr { Assigned by Borland } Version 4.0a (12-12-87): . Set the correct dates for WNDWVARS.TPU and WNDW40.TPU. Version 4.2 (10-22-88): . Major revision over WNDW40; over 50 procedures added or changed. . Added professional documents WNDW42.DOC and WNDWREF.DOC. . Added virtual window power. . Enabled direct writing to hidden windows and virtual screens. . Added multiple video page routines. . Added 28 window relative routines. . Replaced Qbox with MakeWindow RelMode. . Replaced ScrollWindow with WScrollUp, WScrollDown, WInsLine, WDelLine, and WEosLn. . Changed WSwhereR and WSwhereC to be window relative. . Added window-relative stats in WndwStat. . Changed BrdrRec acronyms. . Changed and added window modes. . Added full line drawing procedures. . Changed WndwVars unit to an include file. . Changed ClearWindow to WClrScr . Changed ClearTitle to WClrTitle . Deleted Attr function. Appendix B: Revision History Page 38 WNDW Multi-level Virtual Windows User's Guide, Version 5.X Version 5.X (12-20-88): . Compiled WNDW42 under TP5. No other changes. Appendix B: Revision History Page 39 WNDW Multi-level Virtual Windows User's Guide, Version 5.X A P P E N D I X C : C R E D I T S Fundamental Ideas - The initial concepts of serial-access windows were developed by Michael Burton in his copy of WINDO.INC, ver 2.4. The concepts were used by written permission. Special Effects - Special effects concepts were graciously suggested by Rick Fothergill. Copyright (c) 1986-1988 by James H. LeMay for Eagle Performance Software. All Rights Reserved. Protected by the United States Copyright Laws. Appendix C: Credits Page 40